TwilioのVerifyが提供するAPIを呼び出す際のエラーハンドリングについてまとめてみた

こんばんは、CX事業本部リテールアプリ共創部のmorimorikochanです。

みなさんTwilioは利用されていますか？👀
Twilioにはアプリケーションに簡単にSMS認証を実装できる Verify というサービスがあるのはご存知でしょうか？ このサービスではSMSメッセージを送信する部分やその後の認証コードとの突合処理などをAPIとして提供してくれています。

また、一般的にSMS認証など外部のAPIが関係する機能では特に、 ユーザーが入力した電話番号や認証コードに起因するエラーかそうでないシステム起因のエラーかをはっきりと分けてユーザーに伝えなければならない場合が多い と思います。

そこで今回は、そのようなハンドリングが可能になるように、このサービスが提供するAPIのレスポンスについて調査を行ったので記録として残しておきます。

2024年4月12日現在での内容です。また、利用しているNode.jsのライブラリは`3.84.1`です。アップデートされている可能性があるのでご注意ください

tl;dr

VerifyのAPI	どのような場合	どのようなレスポンスになるか
認証作成API	正常に実行できた場合	ステータスコード=200、特にエラーは発生しない
認証作成API	存在しない電話番号の場合	ステータスコード=400、コード=60200
認証作成API	同一のVerificationに対して認証作成APIを5回以上呼び出した場合	ステータスコード=429、コード=60202
認証チェックAPI	正しい認証コードだった場合	ステータスコード=200、レスポンスボディの statusが approved になる
認証チェックAPI	認証コードが間違っている場合	ステータスコード=200、レスポンスボディの statusが pending になる
認証チェックAPI	認証コードを5回以上間違えた場合	ステータスコード=429、コード=60202
認証チェックAPI	Verification が期限切れ（10分経過）の場合	ステータスコード=404、コード=20404

※全てのパターンを網羅しているわけではありません。ご自身のユースケースに応じて適宜修正が必要です。

Verifyとは？

Verifyには主に2つのAPIが提供されており、SMS認証を実装する際にはこの2つを利用します。

• Start New Verification
  • 以降、認証作成APIと呼びます
• Check a Verification
  • 以降、認証チェックAPIと呼びます

認証作成APIでは、指定した電話番号に認証コード付きのSMSメッセージを送信することができます。 ここでは認証（広義的でややこしいのでVerificationと呼びます）が作成されます。

• Verificationには10分間の有効期限があります。
• Verificationが作成されてから10分間は同じ電話番号でこのAPIを呼び出しても、同じVerificationが再利用されるため、同じ認証コードを含むSMSメッセージが再度送信されます。
• ただし10分以内であれば何度も実行できるわけではなく、最大で5回までとなっています。
  • それを超えると ステータスコード=429, コード=60202 でレスポンスされます
• また、存在しない電話番号の場合は ステータスコード=400, コード=60200 でレスポンスされます
  • ただし、ここでいう「存在しない電話番号」は 00000000000 などの明らかに存在しない電話番号に対しての話です。
  • こちらのサイトで出力できるようなダミーの電話番号の場合はこのケースに該当しません。正常にレスポンスされますが、実際にはSMSメッセージがが送信されていないと思われます。

また、認証チェックAPIでは認証コードと電話番号をもとにそれらの組み合わせが正しいかチェックすることができます。

• 正しい認証コードだった場合は、 ステータスコード=200, レスポンスボディのstatusがapprovedとなった状態 でレスポンスされます
• 間違った認証コードだった場合は、 ステータスコード=200, レスポンスボディのstatusがpendingとなった状態 でレスポンスされます
• また、Verificationが期限切れ（10分）になっている場合は ステータスコード=404, コード=20404 でレスポンスされます。
• また、認証コードを5回以上間違えた場合、それ以降このAPIへの呼び出しは ステータスコード=429, コード=60202 でレスポンスされます。

エラーハンドリングの例

例えばNode.jsのライブラリを利用している場合だと、ライブラリからthrowされるErrorオブジェクトにはcode, status, moreInfoやdetailsなどが含まれているので、以下のように記載できます。

client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
      .verifications
      .create({to: '+15017122661', channel: 'sms'})
      .then(verification => console.log(verification.sid));
      .catch(error => {
        if (error.code === 60200) {
          // 存在しない電話番号の場合
        }
        if (error.code === 60202) {
          // 同一の`Verification`に対して認証作成APIを5回以上呼び出した場合
        }

        // ...
      })

まとめ

VerifyのAPI	どのような場合	どのようなレスポンスになるか
認証作成API	正常に実行できた場合	ステータスコード=200、特にエラーは発生しない
認証作成API	存在しない電話番号の場合	ステータスコード=400、コード=60200
認証作成API	同一のVerificationに対して認証作成APIを5回以上呼び出した場合	ステータスコード=429、コード=60202
認証チェックAPI	正しい認証コードだった場合	ステータスコード=200、レスポンスボディの statusが approved になる
認証チェックAPI	認証コードが間違っている場合	ステータスコード=200、レスポンスボディの statusが pending になる
認証チェックAPI	認証コードを5回以上間違えた場合	ステータスコード=429、コード=60202
認証チェックAPI	Verification が期限切れ（10分経過）の場合	ステータスコード=404、コード=20404

※全てのパターンを網羅しているわけではありません。ご自身のユースケースに応じて適宜修正が必要です。